Pluspack 1/Caligari Corporation Pluspack1 1998.iso/TSX_SDK/tsxINC/tsxPolyh.h

C/C++ Source or Header | 1998-01-28 | 15.6 KB | 381 lines

//******************************************************************************
//    File: tsxPolyh.h
//  Module: trueSpace eXtensions API
//   Descr: Definition of tsxPOLYHEDRA
//******************************************************************************

#ifndef TSXPOLYHEDRA_H
#define TSXPOLYHEDRA_H

#include "tsxTypes.h"


//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

// A tsxPOLYHEDRON is the only renderable simple geometric node type.
// It is basically a geometric object constructed of polygonal faces.
// It contains the following additional info beyond MNode:
//     - Status flags
//     - Vertices
//     - Vertex Transformation Matrix
//     - Faces
//     - Materials
//     - UV space mappings
//     - Bounding Box

// trueSpace divides the traditional model transformation matrix of geometric
// objects into two:
//   - The Model-Axes, which specify the model-frame origin and axes orientation.
//   - The Vertex Transformation Matrix, which specifies the transformation
//     necessary to convert a Polyhedron's vertices into world space coordinates.
//     The coordinates used to specify each vertex in the Polyhedron's vertex
//     array are relative to the Vertex Transformation Matrix.
//  See also tsxGNode.h and tsxMNode.h .


//------------------------------------------------------------------------------
//    Related Types
//------------------------------------------------------------------------------

// Face -> Vertex data
// Note: Use the TSXAPI memory routines (tsxMisc.h) to allocate
//  the memory area for instances of this type.
//  DO NOT use `new' or `malloc/calloc'!
struct CtsxFaceVx
{
    int vix;  // Index into Polyhedron's Vertex Array (see `tsxPolyhGetVxArray').
    int uvix; // Index into Polyhedron's UV Array.
    int nextfaceix;  // Index (in Polyh) of next face containing this vertex.
             // Use `tsxPolyhComputeFaceAdjacency' to set this field.
    CtsxColor color;  //IF color.alpha == 0 THEN use material color
             //OTHERWISE use vertex color.
};

// Face.
// Faces are one-sided polygons, with their vertices specified in clockwise
// order when looking at the front of the polygon. The surface normal points
// out of (or away from) the front.
// Use `tsxPolyhGetFaceptrArray' to access a polyhedron's faces.
// You must use `tsxFaceAlloc' or `tsxFaceCopy' to create instances of this type.
struct CtsxFace
{
    short nbrVxs;    //Nbr of Vertices
    CtsxFaceVx* pFVxs;    //Array of Face-Vertex data, Vertices in clockwise order.
    unsigned char r1;    // reserved
    unsigned char r2;    // reserved
    void *r3;        // reserved
    unsigned char normVxs[3];    //Indices into pFVxs of 3 vertices
                // ... to build Face Normal (see below).
    unsigned short materialIdx;    //ID of Face's material
};

// Note on the field tsxFace.normVxs ...
// The three indices represent three face vertices in clockwise order,
// defining two rays in the plane of the face:
//    ORIGIN -> RAY1  and  ORIGIN -> RAY2
// The cross-product of (ray1 x ray2) gives an unnormalized vector
// perpandicular to the face, facing out. These vertices must not be colinear.
#define tsx_NORM_VXS_ORIGIN  1
#define tsx_NORM_VXS_RAY1    0
#define tsx_NORM_VXS_RAY2    2


// -----------------------------------------------------------------------
// How to create a Polyhedron from scratch
// ---------------------------------------
//
// The following pseudo-code demonstrates how to create a new Polyhedron.
// Actual code should include error tests omitted here.
//
// ... Create the Polyhedron shell
// tsxPOLYHEDRON* pPolyh;
// tsxPolyhCreate( &pPolyh );
// ... Vertices
// CtsxVector3f* pVxs = tsxCalloc( iNbrVxs, sizeof(CtsxVector3f) );
// { Set Vertex coordinates }
// tsxPolyhSetVxs( pPolyh, iNbrVxs, pVxs );
// ... Faces
// CtsxFace** ppFaces = tsxCalloc( iNbrFaces, sizeof(CtsxFace*) );
// for ( i=0; i<iNbrFaces; ++i ) {
//      ... set Face-vertex info
//      CtsxFaceVx* pFVxs = tsxCalloc( NbrVxsForFace[i], sizeof(CtsxFaceVx) );
//      { set fields in pFVxs, especially vix = index into pVxs }
//      ... set Face info
//      CtsxFace* pFace = tsxFaceAlloc();
//      pFace->pFVxs = pFVxs;
//      pFace->nbrVxs = NbrVxsForFace[i];
//      { set the normVxs field, etc. }
//      ... Add face to Face-array
//      ppFaces[i] = pFace;
// }
// tsxPolyhSetFaces( pPolyh, iNbrFaces, ppFaces );
// ... Tell trueSpace to complete Polyhedron internals
// tsxPolyhComputeFaceAdjacency( pPolyh );
// tsxPolyhMarkTopologyChange( pPolyh );
// tsxPolyhMarkGeomChange( pPolyh );
// ... Initialize to default active material
// tsxPolyhInitializeMaterials( pPolyh );
// ... Add to scene and display
// tsxSceneAddObject( (tsxGNODE*)pPolyh, e_tsxFALSE);
// -----------------------------------------------------------------------


//------------------------------------------------------------------------------
//    Managers
//------------------------------------------------------------------------------

// Creates an empty Polyhedron (0 vertices and faces).
// The Model-Axes are set to the World Axes.
// The Vertex Transformation Matrix is set to the identity matrix
// with no translation.
TSXAPIFN tsxERR tsxPolyhCreate( tsxPOLYHEDRON** ppPolyh );

// Clears a Polyhedron to 0 vertices & faces, freeing related structures.
TSXAPIFN void tsxPolyhClear( tsxPOLYHEDRON* pPolyh );

// Tessellate the polyhedron.
// The geometry of the polyhedron is modified so that all faces are triangles.
// If the original polyhedron had some non-triangular faces, then the number
// of faces will probably increase.  Actually replaces the internal face
// and related structures.
TSXAPIFN tsxERR tsxPolyhTessellate( tsxPOLYHEDRON* pPolyh );


//------------------------------------------------------------------------------
//    Status
//------------------------------------------------------------------------------

// The following functions inform trueSpace of changes in a Polyhedron.
// These flags are checked when the object is next drawn, and some topological
// information is computed and cached.

// Tell tS that this Polyhedron's Geometry has changed.
TSXAPIFN void tsxPolyhMarkGeomChange( tsxPOLYHEDRON* pPolyh );

// Tell tS that this Polyhedron's Topology has changed.
TSXAPIFN void tsxPolyhMarkTopologyChange( tsxPOLYHEDRON* pPolyh );

// Tell tS that this Polyhedron's Material(s) have changed.
// Use after modifying UV entries, for example.
TSXAPIFN void tsxPolyhMarkMaterialChange( tsxPOLYHEDRON* pPolyh );

// Tell tS that this Polyhedron's Vertex has changed.
TSXAPIFN void tsxPolyhMarkVertexChange( tsxPOLYHEDRON* pPolyh , long vertex );


//------------------------------------------------------------------------------
//    Vertices
//------------------------------------------------------------------------------

// Get the number of vertices (0 if not a Polyhedron).
TSXAPIFN int tsxPolyhGetNbrVxs( tsxPOLYHEDRON* pPolyh );

// Get pointer to the array of vertices (0 if not a Polyhedron).
// The Vertex coordinates are in the frame defined by
// the Vertex Transformation Matrix.
TSXAPIFN CtsxVector3f* tsxPolyhGetVxArray( tsxPOLYHEDRON* pPolyh );

// Get the Vertex Transformation Matrix. Returns pTxmx, if valid operation.
// Note: This matrix includes scaling and shearing terms, so it is not
// guaranteed to be orthogonal. Use `tsxUnMatrix3f' before inverting.
TSXAPIFN CtsxTxmx3f* tsxPolyhGetVxTxmx(
    tsxPOLYHEDRON* pPolyh,
    CtsxTxmx3f* pTxmx ); //ptr to Txmx where result is copied.

// Assign a new vertex array to the Polyhedron.
// The corresponding field in pPolyh is set to pVxs.
// Clears old Vx array and frees memory, if any.
// Note: Use the TSXAPI memory routines (tsxMisc.h) to allocate
// the memory area (pVxs) for the Vertex Array
// -- DO NOT use `new' or `malloc/calloc'!
TSXAPIFN void tsxPolyhSetVxs(
    tsxPOLYHEDRON* pPolyh,
    int iNbrVxs,        // Number of Vxs (>= 0)
    CtsxVector3f pVxs[] );    // ptr to Array. May be 0.

// Copies a new Vertex Transformation Matrix into pPolyh.
TSXAPIFN void tsxPolyhSetVxTxmx(
    tsxPOLYHEDRON* pPolyh,
    CtsxTxmx3f* pTxmx ); //ptr to new Txmx copied into Polyh.


//------------------------------------------------------------------------------
//    Faces
//------------------------------------------------------------------------------

// The face data is stored as an array of pointers to CtsxFace structures.
// Always use the following functions to manage faces.

// Allocate a new face structure
TSXAPIFN CtsxFace* tsxFaceAlloc();

// Delete's pFace and all related structures.
TSXAPIFN void tsxFaceDelete( CtsxFace* pFace );

// Allocates new Face structure, assigning it to ppFaceCopy,
// and Copies pFace and all related structures into it.
TSXAPIFN tsxERR tsxFaceCopy( CtsxFace** ppFaceCopy, CtsxFace* pFace );

// Get the number of Faces (0 if not a Polyhedron).
TSXAPIFN int tsxPolyhGetNbrFaces( tsxPOLYHEDRON* pPolyh );

// Get pointer to the array of Face-ptrs (0 if not a Polyhedron).
TSXAPIFN CtsxFace** tsxPolyhGetFaceptrArray( tsxPOLYHEDRON* pPolyh );

// Assign a new Face-ptr array to the Polyhedron.
// The corresponding field in pPolyh is set to pFaces.
// Clears old Faces and array and frees memory, if any.
// Note: Use the TSXAPI memory routines (tsxMisc.h) to allocate
// the memory area (pFaces) for the Face Array
// -- DO NOT use `new' or `malloc/calloc'!
TSXAPIFN void tsxPolyhSetFaces(
    tsxPOLYHEDRON* pPolyh,
    int iNbrFaces,        // Number of Faces (>= 0)
    CtsxFace* pFaces[] );    // Array of ptrs. May be 0.

// Uses pFace->normVxs to compute face normal of pFace in pPolyh.
// Normal returned in pNorm, in the frame defined by the
// Vertex Transformation Matrix.
TSXAPIFN void tsxPolyhGetFaceNormal(
    tsxPOLYHEDRON* pPolyh,
    CtsxFace* pFace,
    CtsxVector3f* pNorm ); //ptr to struct where result is copied.

// Sets up the `nextfaceix' fields in CtsxFaceVx structs.
// Call after all the other Face-Vertex data has been set for all faces.
TSXAPIFN tsxERR tsxPolyhComputeFaceAdjacency( tsxPOLYHEDRON* pPolyh );


//------------------------------------------------------------------------------
//    UV Space
//------------------------------------------------------------------------------

// Every polyhedron maintains an array of UV entries.
// CtsxFaceVx.uvix is an index into this array, giving the UV coordinates
// for that vertex for the corresponding face's material.

// Get the number of entries in UV-array (0 if not a Polyhedron).
TSXAPIFN int tsxPolyhGetNbrUV( tsxPOLYHEDRON* pPolyh );

// Get pointer to the UV-array (0 if not a Polyhedron).
TSXAPIFN CtsxUV* tsxPolyhGetUVArray( tsxPOLYHEDRON* pPolyh );

// Assign a new UV array to the Polyhedron.
// The corresponding field in pPolyh is set to pUV.
// Clears old Faces and array and frees memory, if any.
// Note: Use the TSXAPI memory routines (tsxMisc.h) to allocate
// the memory area (pUV) for the UV Array -- DO NOT use `new' or `malloc/calloc'!
TSXAPIFN void tsxPolyhSetUVArray(
    tsxPOLYHEDRON* pPolyh,
    int iNbrUV,        // Number of UV entries (>= 0)
    CtsxUV *pUV );    // ptr to UV-Array. May be 0.


//------------------------------------------------------------------------------
//    Painting/Materials
//------------------------------------------------------------------------------

// Assigns active material to entire Polyhedron.
// Call this function AFTER setting/modifying a polyhedron's geometry,
// and BEFORE painting faces or vertices.
// Use other material functions to specify specific materials.
TSXAPIFN tsxERR tsxPolyhInitializeMaterials( tsxPOLYHEDRON* pPolyh );

// Give entire pPolyh the material pMatrl. Remove old materials.
// Note: A copy of pMatrl is created and assigned to the Polyhedron.
//       Caller is responsible for managing pMatrl.
TSXAPIFN void tsxPolyhPaint( tsxPOLYHEDRON* pPolyh, tsxMATERIAL* pMatrl );

// Paint face with a material.
// Returns e_tsxFALSE on failure or if object not changed.
// Note: A copy of pMatrl is created and assigned to the Polyhedron.
//       Caller is responsible for managing pMatrl.
TSXAPIFN tsxBOOL tsxPolyhPaintFace(
    tsxPOLYHEDRON* pPolyh,
    int iFaceIndex,        //Index of face to be painted in pPolyh
    tsxMATERIAL* pMatrl,    //New material to paint on face
    tsxBOOL bClearVxColors    //e_tsxTRUE if Vertex colors should be cleared.
    );

// Paint vertex with a color.
// Returns e_tsxFALSE on failure or if object not changed.
// Note: A copy of pColor is created and assigned to the Polyhedron.
//       Caller is responsible for managing pColor.
TSXAPIFN tsxBOOL tsxPolyhPaintVertex(
    tsxPOLYHEDRON* pPolyh,
    int iVxIndex,        //Index of face to be painted in pPolyh
    CtsxColor* pColor        //New color to paint on face
    );

// Use this function to access the material assigned to a face.
// pMatrl is a pointer to a Material object created through one of the
// tsxMaterialCreate functions. The face's material, if any, is copied
// into this structure.
// Returns e_tsxFALSE on failure or if face does not have a material.
TSXAPIFN tsxBOOL tsxPolyhGetMaterial(
    tsxPOLYHEDRON* pPolyh,
    unsigned short materialIdx,  //From CtsxFace.materialIdx
    tsxMATERIAL* pMatrl         //Material copied into this structure
    );

// Photo-render a face in the active view.
TSXAPIFN tsxERR tsxPolyhPhrenderFace( tsxPOLYHEDRON* pPolyh, int iFaceIndex );


//------------------------------------------------------------------------------
//    Primitive Polyhedron Shapes
//------------------------------------------------------------------------------

// These are the same functions as used in the tS interface.
// They all create an object centered at the origin,
// painted with the currently active material.
// Where there is no specific input, the X, Y, Z dimensions default to 2.
// Since these are all polyhedra, with a piecewise linear approximation
// of curved surfaces, the resolution of this approximation is controlled
// by the NbrLongitudes and NbrLattitudes parameters.

// Creates a sphere sitting on the XY plane, with Z as the vertical axis.
TSXAPIFN tsxPOLYHEDRON* tsxCreateSphere(
    int NbrLongitudes,    // # Longs (Min = 3)
    int NbrLattitudes,    // # Latts (Min = 2)
    float radius );

// Creates a Cylinder with the base in the XY plane and Z as the vertical axis.
TSXAPIFN tsxPOLYHEDRON* tsxCreateCylinder(
    int NbrLongitudes,    // # Longs (Min = 3)
    int NbrLattitudes,    // # Latts (Min = 2)
    float topRadius,    // Top radius
    float botRadius,    // Base radius
    float height );

// Creates a Cone (really a cylinder with a very very small top)
// with the base in the XY plae, and Z as the vertical axis.
TSXAPIFN tsxPOLYHEDRON* tsxCreateCone(
    int NbrLongitudes,    // # Longitudes (Min = 3)
    int NbrLattitudes,    // # Lattitudes (Min = 2)
    float botRadius,    // Base radius
    float height );

// Creates a cube aligned with the World axes.
TSXAPIFN tsxPOLYHEDRON* tsxCreateCube(
    int nbrSections,
    float x,
    float y,
    float z );

// Create a torus with Z as the axis.
TSXAPIFN tsxPOLYHEDRON* tsxCreateTorus(
    int NbrLongitudes,    // # Longitudes (Min = 3)
    int NbrLattitudes,    // # Lattitudes (Min = 3)
    float innerRadius ); // Inner radius (0 < radius < 1.0)

// Creates rectangular plane in XY plane.
TSXAPIFN tsxPOLYHEDRON* tsxCreatePlane(
    int nbrXrects,    // # rects in X direction (Min = 1)
    int nbrYrects );    // # rects in Y direction (Min = 1)


//******************************************************************************
#endif // TSXPOLYHEDRA_H